/*
 *  Copyright (C) 2009  Peter Kist & Jan Ripke
 *
 *  This program is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

#ifndef __mediator_consumer_h
#define __mediator_consumer_h 1

#include <Util/ConcurrentList.h>
#include <Core/Mediator/Interface.h>

namespace galaxy {

    namespace mediator {

        class Consumer
        {
            util::ConcurrentList<Event*> events;

        public:
            Consumer(void);
            virtual ~Consumer(void);

            /** The consumer's type */
            virtual const char * consumerType () = 0;
            /** handle event that is posted POST_IMMEDIATE (see PostMethod in mediator::InterMediator::postEvent) */
            virtual void handleEvent (Event& event) = 0;
            /** handle event that is posted POST_DELAYED (see PostMethod in mediator::InterMediator::postEvent). 
            * \param event The event to handle
            * \return true upon successful handling or false upon error
            */
            virtual bool handleQueuedEvent (Event& event) { return false; };

            /** Handle up to \b max_events events. This method will also terminate the event (free its resources)
            * after it has been handled. For each queued event the method handleQueuedEvent will be called.
            * It will process the number of specified events (max_events) or all the events if the amount 
            * of queued events is less than max_events.
            *
            * If handleQueuedEvent returns error (false), then an error is logged and the event is terminated. Any
            * events that follow in the queue will be processed as normal (the processing loop will not terminate).
            * \param max_events The maximum number of events that is handled.
            */
            void handleDelayedEvents (int max_events);

            /** Check if the consumer has any queued events pending
            * \return true if events are queued or false if queue is empty */
            bool hasEvents () { return ! events.empty(); };
            /** Push an event onto the queue
            * \param event The event to push onto the queue
            * \return true upon success, false upon failure
            */
            bool pushEvent (Event& event);
            /** Pop an event from the queue.
            * \param event A reference to an event pointer that will contain the popped event
            * \return true if event was fetched or false when queue was empty
            */
            bool popEvent (Event*& event);
            /** flush all pending events from the queue (empties the queue without handling the threads) */
            void flushEvents ();
            /** destroy the event, freeing its resources */
            void terminateEvent (Event * event);
        };

    } // namespace mediator

} // namespace galaxy

#endif // __mediator_consumer_h
